3 Amazon Simple Email Service (AWS SES)

If you just want to send e-mails using your non-SES infrastructure, this plugin won't help you, I recommend you to use the great Grails Mail Plugin (http://grails.org/plugin/mail).

Unfortunately, SES does not provide a simple SMTP server address to connect and use, otherwise we could just configure the Grails Mail Plugin to use it. Instead of this, AWS provides a http web service for it.

But, if you really want to use Mail Plugin, you can configure AWS SES with a SMTP Bridge to connect to your SMTP server, but only if you're running Postfix or Sendmail locally. For doing this, check AWS SES Developer Guide.

You have to be subscribed to SES, if you are not yet, do it before using the plugin.

.h3 Interacting with SES

Grails AWS Plugin adds two types of interacting with AWS Simple Email Service.

3.1 SES Gant scripts

3.1.1 Operation VerifyEmail

To to so, you can run the script:

grails aws-ses-verify-email

You'll be prompted about the e-mail address to verify. After that, SWS will send an confirmation e-mail to this address, you should click on the link in that e-mail to start sending emails using this from.

You will have to do it for all emails you want to use with SES.

3.1.2 Operation ListVerifiedEmails

To use:

grails aws-ses-list-verified-emails

3.1.3 Operation GetSendQuota

grails aws-ses-get-send-quota

3.1.4 Operation GetSendStatistics

Returns the user's sending statistics (the amount of sent mails, bounced, spammed and etc). The output is a list of items, for the last two weeks of sending activity. Each item in the list contains statistics for a 15-minute interval.

grails aws-ses-get-send-statistics

3.1.5 Testing your verified email

Attention: If you only subscribed to Amazon SES and still didn't get access for production using, you'll only be allowed to send e-mails 'from' AND 'to' emais that has been verified with amazon. So, you'll have to use the 'grails aws-ses-verify-email' for both sender and recipient adresses. After getting production access, this won't be needed.

This script is a simple utility to test if amazon has verified your email correctly.

It will queue one test email message for SES. You'll be prompted for the FROM email address and the TO email address to send. Remember, you have to verify these emails first.

grails aws-ses-send-ping-mail

3.2 Sending mail from your application

Attention: If you only subscribed to Amazon SES and still didn't get access for production using, you'll only be allowed to send e-mails 'from' AND 'to' emais that has been verified with amazon. So, you'll have to use the 'grails aws-ses-verify-email' for both sender and recipient adresses. After getting production access, this won't be needed.

Sending e-mails from your application is easy, and you can do it from your services or controllers just calling the sesMail closure that is injected on these artifacts.

class SesTestController {
    def sendPlainTextMail = {
        def mailId = sesMail {
            to "test-email@gmail.com"
            subject "test plain text mail"
            body "sendPlainTextMail (${new Date().format('dd/MM/yyyy HH:mm')})"
        }
        render "E-mail sent: ${mailId}"
    }
}

3.2.1 Configuring the SES options

enabled

The plugin is enabled by default on all environments, you can set 'enabled=false' on some environments to disable email sending. This is useful on testing environments where integration tests runs.

catchall

If you set the 'catch all' address, it will override any other address you set in 'to', 'cc' and 'bcc' properties. This is useful when you have acceptance tests or other environments/uses that you want your mails to be sent, but not to the usual addresses, but to one and only one address.

Any attemp to send emails with this property configured, will send e-mails to the address configured, with no 'cc' and 'bcc' addresses.

from

The default 'from' address to be used. You can override this parameter in every call to the plugin, setting the 'from' parameter. As said before, this address have to be verified with AWS (check Gant scripts section to see how to do it).

Configuration example

To configure it, you'll do the following inside the grails.plugin.aws section of your application Config.

grails {
   plugin {
      aws {
         ses {
            enabled = false
            catchall = "allmailforme@gmail.com"
            from = "my-verified-email@gmail.com"
         }
      }
   }
}

3.2.2 Sending text emails

def mailId = sesMail {
    from "origin@gmail.com"
    to "test-email@gmail.com"
    subject "test plain text mail"
    body "this is the e-mail content, sent at: (${new Date().format('dd/MM/yyyy HH:mm')})"
}

The sesMail returns an unique identifier for this e-mail at Amazon infrastructure, as this one:

0000012dcde0ea1c-d331d2ec-3972-4a6c-825f-fc980cde3352-000000

Amazon don't provide anything useful to do with this id yet, but I imagine that in a near future, you'll be able to retrieve if this email was delivered correctly, or if it was spammed or bounced. So, feel free to store it if you want to.

Closure parameters

AWS Credentials

As the S3 file upload support, you can override AWS credentials settings for sending mails. This is rare and unusual, but if you really need, do the same as in S3.

credentials "new-access-key", "new-secret-key"

Just remember, if this new AWS credentials belong to another AWS account, this account will have to be subscribed to SES service and have verified e-mails to send.

Defining the sender

As seen in the other topic, you can set this default address in the application Config, but if you want to explicitly set the address in each email you send, just override the from method:

from "my-other-email@gmail.com"

Defining recipient e-mails

To

To set the recipient e-mail, use the to method.

to "user@myapp.com"

You can send to multiple addresses doing this:

to "usermyapp.com", "user2myapp.com", "user3@myapp.com"

CC and BCC

To set CC and BCC addresses, you can do the same as to addresses:

cc "copied@myapp.com"

bcc "you-dont-know-me@myapp.com"

And again, for multiple addresses:

ccc "user1@myapp.com", "user2@myapp.com", "user3@myapp.com"

bcc "user4@myapp.com", "user5@myapp.com", "user6@myapp.com"

Setting the e-mail subject

To set the subject, following other parameters convention:

subject "Testing the AWS Plugin"

E-mail body

And finally, the e-mail body can be set with:

body "This is the text user will receive in the e-mail body"

3.2.3 Sending HTML emails

sesMail {
   to "email@gmailcom"
   subject "testing html emails"
   html "<html><body><h3>HTML email</h3><strong>Strong text</strong></body></html>"
}

Using GSP templates to generate html emails

I bet you don't want to write all the HTML in your closure, so, you can design your e-mail in a grails template and use it to define the email content:

sesMail {
   to "email@gmailcom"
   subject "testing html emails"
   html g.render(template: "/email-templates/template", model: [name: "Lucas", now: new Date()])
}

This will render the /email-templates/_template.gsp passing the model map to the rendering engine. For example, let's imagine this file has the following content:

<html>
   <body>
      <h2>Testing e-mail templates</h2>
      <ul>
         <li>Name: ${name}</li>
         <li>Now: ${now.format('dd/MM/yyyy HH:mm')}</li>
      </ul>
   </body>
</html>

This will send the html e-mail with the content below rendered:

<html>
   <body>
      <h2>Testing e-mail templates</h2>
      <ul>
         <li>Name: Lucas</li>
         <li>Now: 28/01/2010 18:02</li>
      </ul>
   </body>
</html>

You can use both methods html and body to send e-mails with both content in it. This is usually the best approach, since user may not allowed his email client to render html emails. So, it is up to you.